Autogenerated HTML docs for v2.6.0-rc2
diff --git a/technical/api-index.html b/technical/api-index.html index 43f6b6d..74dca3c 100644 --- a/technical/api-index.html +++ b/technical/api-index.html
@@ -898,7 +898,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2015-09-08 16:57:36 PDT +Last updated 2015-09-14 14:09:25 PDT </div> </div> </body>
diff --git a/technical/pack-protocol.html b/technical/pack-protocol.html index 7c55863..8d849a2 100644 --- a/technical/pack-protocol.html +++ b/technical/pack-protocol.html
@@ -752,6 +752,15 @@ </div> </div> <div class="sect1"> +<h2 id="_pkt_line_format">pkt-line Format</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The descriptions below build on the pkt-line format described in +protocol-common.txt. When the grammar indicate <code>PKT-LINE(...)</code>, unless +otherwise noted the usual pkt-line LF rules apply: the sender SHOULD +include a LF, but the receiver MUST NOT complain if it is not present.</p></div> +</div> +</div> +<div class="sect1"> <h2 id="_transports">Transports</h2> <div class="sectionbody"> <div class="paragraph"><p>There are three transports over which the packfile protocol is @@ -897,8 +906,6 @@ 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{} 0000</code></pre> </div></div> -<div class="paragraph"><p>Server SHOULD terminate each non-flush line using LF ("\n") terminator; -client MUST NOT complain if there is no terminator.</p></div> <div class="paragraph"><p>The returned response is a pkt-line stream describing each ref and its current value. The stream MUST be sorted by name according to the C locale ordering.</p></div> @@ -916,15 +923,15 @@ flush-pkt no-refs = PKT-LINE(zero-id SP "capabilities^{}" - NUL capability-list LF) + NUL capability-list) list-of-refs = first-ref *other-ref first-ref = PKT-LINE(obj-id SP refname - NUL capability-list LF) + NUL capability-list) other-ref = PKT-LINE(other-tip / other-peeled) - other-tip = obj-id SP refname LF - other-peeled = obj-id SP refname "^{}" LF + other-tip = obj-id SP refname + other-peeled = obj-id SP refname "^{}" shallow = PKT-LINE("shallow" SP obj-id) @@ -966,8 +973,8 @@ depth-request = PKT-LINE("deepen" SP depth) - first-want = PKT-LINE("want" SP obj-id SP capability-list LF) - additional-want = PKT-LINE("want" SP obj-id LF) + first-want = PKT-LINE("want" SP obj-id SP capability-list) + additional-want = PKT-LINE("want" SP obj-id) depth = 1*DIGIT</code></pre> </div></div> @@ -1026,7 +1033,7 @@ compute-end have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) + have-line = PKT-LINE("have" SP obj-id) compute-end = flush-pkt / PKT-LINE("done")</code></pre> </div></div> <div class="paragraph"><p>If the server reads <em>have</em> lines, it then will respond by ACKing any @@ -1106,10 +1113,10 @@ <div class="listingblock"> <div class="content"> <pre><code> server-response = *ack_multi ack / nak - ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF) + ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" - ack = PKT-LINE("ACK SP obj-id LF) - nak = PKT-LINE("NAK" LF)</code></pre> + ack = PKT-LINE("ACK" SP obj-id) + nak = PKT-LINE("NAK")</code></pre> </div></div> <div class="paragraph"><p>A simple clone may look like this (with no <em>have</em> lines):</p></div> <div class="listingblock"> @@ -1219,10 +1226,10 @@ <div class="content"> <pre><code> update-request = *shallow ( command-list | push-cert ) [packfile] - shallow = PKT-LINE("shallow" SP obj-id LF) + shallow = PKT-LINE("shallow" SP obj-id) - command-list = PKT-LINE(command NUL capability-list LF) - *PKT-LINE(command LF) + command-list = PKT-LINE(command NUL capability-list) + *PKT-LINE(command) flush-pkt command = create / delete / update @@ -1269,7 +1276,8 @@ <div class="sectionbody"> <div class="paragraph"><p>A push certificate begins with a set of header lines. After the header and an empty line, the protocol commands follow, one per -line.</p></div> +line. Note that the the trailing LF in push-cert PKT-LINEs is <em>not</em> +optional; it must be present.</p></div> <div class="paragraph"><p>Currently, the following header fields are defined:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> @@ -1324,12 +1332,12 @@ 1*(command-status) flush-pkt - unpack-status = PKT-LINE("unpack" SP unpack-result LF) + unpack-status = PKT-LINE("unpack" SP unpack-result) unpack-result = "ok" / error-msg command-status = command-ok / command-fail - command-ok = PKT-LINE("ok" SP refname LF) - command-fail = PKT-LINE("ng" SP refname SP error-msg LF) + command-ok = PKT-LINE("ok" SP refname) + command-fail = PKT-LINE("ng" SP refname SP error-msg) error-msg = 1*(OCTECT) ; where not "ok"</code></pre> </div></div> @@ -1363,7 +1371,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2015-06-16 15:07:26 PDT +Last updated 2015-09-14 14:08:19 PDT </div> </div> </body> diff --git a/technical/pack-protocol.txt b/technical/pack-protocol.txt index 4064fc7..c6977bb 100644 --- a/technical/pack-protocol.txt +++ b/technical/pack-protocol.txt
@@ -14,6 +14,14 @@ currently on the server, then for the two to negotiate the smallest amount of data to send in order to fully update one or the other. +pkt-line Format +--------------- + +The descriptions below build on the pkt-line format described in +protocol-common.txt. When the grammar indicate `PKT-LINE(...)`, unless +otherwise noted the usual pkt-line LF rules apply: the sender SHOULD +include a LF, but the receiver MUST NOT complain if it is not present. + Transports ---------- There are three transports over which the packfile protocol is @@ -143,9 +151,6 @@ 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{} 0000 -Server SHOULD terminate each non-flush line using LF ("\n") terminator; -client MUST NOT complain if there is no terminator. - The returned response is a pkt-line stream describing each ref and its current value. The stream MUST be sorted by name according to the C locale ordering. @@ -165,15 +170,15 @@ flush-pkt no-refs = PKT-LINE(zero-id SP "capabilities^{}" - NUL capability-list LF) + NUL capability-list) list-of-refs = first-ref *other-ref first-ref = PKT-LINE(obj-id SP refname - NUL capability-list LF) + NUL capability-list) other-ref = PKT-LINE(other-tip / other-peeled) - other-tip = obj-id SP refname LF - other-peeled = obj-id SP refname "^{}" LF + other-tip = obj-id SP refname + other-peeled = obj-id SP refname "^{}" shallow = PKT-LINE("shallow" SP obj-id) @@ -216,8 +221,8 @@ depth-request = PKT-LINE("deepen" SP depth) - first-want = PKT-LINE("want" SP obj-id SP capability-list LF) - additional-want = PKT-LINE("want" SP obj-id LF) + first-want = PKT-LINE("want" SP obj-id SP capability-list) + additional-want = PKT-LINE("want" SP obj-id) depth = 1*DIGIT ---- @@ -284,7 +289,7 @@ compute-end have-list = *have-line - have-line = PKT-LINE("have" SP obj-id LF) + have-line = PKT-LINE("have" SP obj-id) compute-end = flush-pkt / PKT-LINE("done") ---- @@ -348,10 +353,10 @@ ---- server-response = *ack_multi ack / nak - ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF) + ack_multi = PKT-LINE("ACK" SP obj-id ack_status) ack_status = "continue" / "common" / "ready" - ack = PKT-LINE("ACK SP obj-id LF) - nak = PKT-LINE("NAK" LF) + ack = PKT-LINE("ACK" SP obj-id) + nak = PKT-LINE("NAK") ---- A simple clone may look like this (with no 'have' lines): @@ -467,10 +472,10 @@ ---- update-request = *shallow ( command-list | push-cert ) [packfile] - shallow = PKT-LINE("shallow" SP obj-id LF) + shallow = PKT-LINE("shallow" SP obj-id) - command-list = PKT-LINE(command NUL capability-list LF) - *PKT-LINE(command LF) + command-list = PKT-LINE(command NUL capability-list) + *PKT-LINE(command) flush-pkt command = create / delete / update @@ -521,7 +526,8 @@ A push certificate begins with a set of header lines. After the header and an empty line, the protocol commands follow, one per -line. +line. Note that the the trailing LF in push-cert PKT-LINEs is _not_ +optional; it must be present. Currently, the following header fields are defined: @@ -560,12 +566,12 @@ 1*(command-status) flush-pkt - unpack-status = PKT-LINE("unpack" SP unpack-result LF) + unpack-status = PKT-LINE("unpack" SP unpack-result) unpack-result = "ok" / error-msg command-status = command-ok / command-fail - command-ok = PKT-LINE("ok" SP refname LF) - command-fail = PKT-LINE("ng" SP refname SP error-msg LF) + command-ok = PKT-LINE("ok" SP refname) + command-fail = PKT-LINE("ng" SP refname SP error-msg) error-msg = 1*(OCTECT) ; where not "ok" ---- diff --git a/technical/protocol-common.html b/technical/protocol-common.html index 206f1de..96859fd 100644 --- a/technical/protocol-common.html +++ b/technical/protocol-common.html
@@ -820,7 +820,10 @@ <div class="paragraph"><p>A pkt-line MAY contain binary data, so implementors MUST ensure pkt-line parsing/formatting routines are 8-bit clean.</p></div> <div class="paragraph"><p>A non-binary line SHOULD BE terminated by an LF, which if present -MUST be included in the total length.</p></div> +MUST be included in the total length. Receivers MUST treat pkt-lines +with non-binary data the same whether or not they contain the trailing +LF (stripping the LF if present, and not complaining when it is +missing).</p></div> <div class="paragraph"><p>The maximum length of a pkt-line’s data component is 65520 bytes. Implementations MUST NOT send pkt-line whose length exceeds 65524 (65520 bytes of payload + 4 bytes of length data).</p></div> @@ -854,7 +857,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-04-08 12:47:26 PDT +Last updated 2015-09-14 14:08:19 PDT </div> </div> </body>
diff --git a/technical/protocol-common.txt b/technical/protocol-common.txt index 889985f..bf30167 100644 --- a/technical/protocol-common.txt +++ b/technical/protocol-common.txt
@@ -62,7 +62,10 @@ pkt-line parsing/formatting routines are 8-bit clean. A non-binary line SHOULD BE terminated by an LF, which if present -MUST be included in the total length. +MUST be included in the total length. Receivers MUST treat pkt-lines +with non-binary data the same whether or not they contain the trailing +LF (stripping the LF if present, and not complaining when it is +missing). The maximum length of a pkt-line's data component is 65520 bytes. Implementations MUST NOT send pkt-line whose length exceeds 65524
